home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 January: Mac OS SDK / Dev.CD Jan 97 SDK2.toast / Development Kits (Disc 2) / OpenDoc / OpenDoc Development / Debugging Support / OpenDoc™ Source Code / Storage / Bento / CM / CMAPIDbg.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-08-28  |  5.1 KB  |  117 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        CMAPIDbg.h
  3.  
  4.     Contains:    Container Manager Global Name Values Interfaces
  5.  
  6.     Written by:    Ira L. Ruben
  7.  
  8.     Owned by:    Ed Lai
  9.  
  10.     Copyright:    © 1992 - 1994 by Apple Computer, Inc., all rights reserved.
  11.  
  12.     Change History (most recent first):
  13.  
  14.          <2>     8/26/94    EL        #1181622 Ownership update.
  15.  
  16.     To Do:
  17. */
  18.  
  19. /*---------------------------------------------------------------------------*
  20.  |                                                                           |
  21.  |                           <<< CM_API_Debug.h >>>                          |
  22.  |                                                                           |
  23.  |              Container Manager Global Name Values Interfaces              |
  24.  |                                                                           |
  25.  |                               Ira L. Ruben                                |
  26.  |                                  3/30/92                                  |
  27.  |                                                                           |
  28.  |                    Copyright Apple Computer, Inc. 1992-1994               |
  29.  |                           All rights reserved.                            |
  30.  |                                                                           |
  31.  *---------------------------------------------------------------------------*
  32.  
  33.  This file defines a set of special debugging API routines and switches.  They are kept
  34.  separate from the API since they may or may not be supported in a particular installation.
  35.  
  36.  There are three routines:
  37.  
  38.      1. CMDebugging()                    - to set some internal debugging "options"
  39.     2. CMDumpTOCStructures()    - to dump in-memory TOC as a tree-like format
  40.     3. CMDumpContainerTOC()        - to read in container TOC and display it in a table format
  41. */
  42.  
  43. #ifndef __CM_API_DEBUG__
  44. #define __CM_API_DEBUG__
  45.  
  46. #include <stdio.h>
  47.  
  48. #ifndef __CM_API__
  49. #include "CMAPI.h"
  50. #endif
  51.  
  52.  
  53. /*                        C A U T I O N   A N D   N O T E!                                                            */
  54. /*                        --------------------------------                                                            */
  55.  
  56. /* In order to be able to use these routines the Container Manager API code must have        */
  57. /* the routines defined!  They may be suppressed as a function of the installation.          */
  58. /* Thus this file should NOT be supplied if the Container Manager is built with these     */
  59. /* suppressed.  Even if it is, it is left up to the builder is s/he wants these routines*/
  60. /* publically known.                                                                                                                                        */
  61.  
  62.  
  63.                                                                          CM_CFUNCTIONS
  64.  
  65. void CM_FIXEDARGS CMDebugging(CMSession sessionData, CM_USHORT tocTableSize, 
  66.                                                             FILE CM_PTR *debuggingFile, CMBoolean doValidations);
  67.     /*
  68.     This routine provides some debugging "options" to the API.  It must be called AFTER 
  69.      CMStartSession() but BEFORE any containers are opened.  It takes the session global data
  70.   pointer returned by CMStartSession() and adds (actually modifies) some of the data there
  71.   to enable debugging.
  72.     
  73.     The current options that can be set are:
  74.     
  75.     1. The size of the TOC index tables.  If 0 is passed, the default is used.  The 
  76.          current in-memory TOC implementation scheme utilizes index tables.  Each level of
  77.          table represents one digit of an object descriptor ID.  For ID=123 there are three
  78.          tables.  A hundereds table, a tens table, and finally the unit (lowest level)
  79.          table.  The i'th entry of a table points to the next lower table.  The lowest
  80.          table of course points to the object itself in memory.  The tocTableSize determines
  81.          the size of these tables.  The current defualt is 256.
  82.     
  83.     2. A FILE* debugging output variable. It is usually stdout, stderr, or NULL. For NULL,
  84.          no debugging output is produced.  Currently this thing is used to display the TOC
  85.          as a table when it is open for input (if CMDUMPTOC was set).
  86.               
  87.     3. The dynamic switch controlling the refNum validations (e.g., checking for NULL) and
  88.          various other protections.  If set to 0 the protection checks are suppressed.  If
  89.          nonzero they are performed, but only if the protection code is present.  On a per-
  90.          installation basis it may be suppressed.  In that case the switch has no effect.
  91. */
  92.  
  93.  
  94. void CM_FIXEDARGS CMDumpTOCStructures(CMContainer container, FILE CM_PTR *f);
  95.     /*
  96.     This routine is used for internal debugging of the TOC data structures for the specified
  97.     container.  It displays their current state to the (open) file associated with the
  98.     specified file variable, f.
  99.     */
  100.  
  101.  
  102. void CM_FIXEDARGS CMDumpContainerTOC(CMconst_CMContainer container, FILE CM_PTR *f,
  103.                                                                         const CM_ULONG tocOffset, const CM_ULONG tocSize);
  104.     /*
  105.     This routine is used for internal debugging of the TOC data as it appears in its final
  106.     form in the container itself.  The entire TOC in the container, starting at container
  107.     offset tocOffset for tocSize bytes, is displayed to the (open) file associated with the
  108.     file variable f.  It is formatted, but otherwise  unchanged.  You can use this routine to
  109.     see if the TOC was correctly written to its container.
  110.     
  111.     Note, the container's handler routines are used to do the positioning and reading.  It
  112.     is assumed that the passed tocOffset and tocSize are valid (from a container label).
  113.     */
  114.  
  115.                                                                     CM_END_CFUNCTIONS
  116. #endif
  117.